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1. Generalities 

In this documentation file, we briefly describe how to run the MC@NLO, imple- 
mented according to the formalism introduced in ref. [1]. The following production 
processes are now available (IPROC has the same meaning as in HERWIG [2]): 



IPROC 


Process 


2850 


H X E 2 -> W+W~ + A 


2860 


H 1 H 2 -> ZZ+A 


2870 


H 1 H 2 -> W+Z+A 


2880 


E X E 2 -> W-Z+A 



Table 1: Processes implemented in MC@NLO. 
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1.1 Mode of operation 

In the case of standard MC, a hard kinematical configuration is generated on a event- 
by-event basis, and it is subsequently showered and hadronized. In the case of our 
MC@NLO, all of the hard kinematical configurations are generated in advance, and 
stored in a file (which we call event file - see sect. 3.1); the event file is then read by 
HERWIG, which showers and hadronizes each hard configuration. Therefore, in the 
MC@NLO the reading of a hard configuration from the event file is equivalent to the 
generation of such a configuration in the standard MC. Apart from this difference, 
MC@NLO and MC behave exactly in the same way. Thus, the available user's 
analysis routines can be used without any modification in the case of MC@NLO. One 
should recall, however, that MC@NLO always generates some events with negative 
weights (see ref. [1]); therefore, the correct distributions are obtained by summing 
weights with their signs (i.e., the absolute values of the weights must NOT be used 
when filling the histograms). 

With such a structure, it is natural to create two separate executables, which 
we improperly denote as NLO and MC. The former has the sole scope of creating 
the event file; the latter is just HERWIG, augmented by the capability of reading the 
event file. 

1.2 Package files 

The package consists of the following files: 

• Shell utilities 

MCatNLO. Script 
MCatNLO. inputs 
Makefile 

• General purpose codes 
alpha . f 

dummies . f 
linux . f 

mcatnlo_date . f 
mcatnlo_int . f 
mcatnlo_libof pdf . f 
mcatnlo_mlmtopdf .f 
mcatnlo_pdf tomlm . f 
mcatnlo_str . f 
mcatnlo_uti . f 
mcatnlo_uxdate . c 
sun.f 
trapf pe . c 
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• Vector boson pair production codes 
mcatnlo_hwanal . f 
mcatnlojiwdriver . f 
mcatnlo_hwhvvj . f 
mcatnlo_vbmain . f 
mcatnlo_vbxsec . f 

These files can be downloaded from the Web page: 

http : / /www . hep . phy . cam . ac . uk/ theory/ webber/MCatNLO 
The vector boson pair production codes and shell utilities are only relevant to the 
production of W + W~, ZZ, and W ± Z pairs in hadronic collisions. The general purpose 
codes will be used in the MC@NLO implementation of other production processes. 

In addition to the files listed above, the user will need a version of the HERWIG 
code, which can be downloaded from the Web page: 

http : / /hepwww . rl . ac . uk/ theory/seymour/herwig/ 
As stressed in ref. [1], for the MC@NLO we don't need to modify the existing (LL) 
shower algorithm; thus, users can simply link (some of) the files above to their 
preferred HERWIG version. To be capable of handling the relevant event process 
codes listed in table 1, this should be public version 6.301 or higher. On most systems, 
users will need to delete the dummy subroutines HWHVVJ, PDFSET and STRUCTM 
from the standard HERWIG package, to permit linkage of the corresponding routines 
from the MC@NLO package. 

1.3 Working environment 

We have written a number of shell scripts and a Makefile (all listed under Shell 
utilities above) which will simplify the use of the package considerably. To use them, 
the computing system must support bash shell, and gmake. Should these be unavail- 
able on the user's computing system, the compilation and running of our MC@NLO 
requires more detailed instructions, for which we refer the reader to app. A. This 
appendix will also serve as a reference for more advanced usage of the package. 

1.4 Source and running directories 

We assume that all the files of the package sit in the same directory, which we call 
the source directory. When creating the executable, our shell scripts determine the 
type of operating system, and create a subdirectory of the source directory, which 
we call the running directory, whose name is Alpha, Sun, or Linux, depending on 
the operating system. If the operating system is not known by our scripts, the name 
of the working directory is Run. The running directory contains all the object files 
and executable files, and in general all the files produced by the MC@NLO while 
running. It must also contain the relevant grid files (see sect. 2.1), or links to them, 
if the library of parton densities provided in the package is used. 
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2. Prior to running 



Before running the code, the user needs to edit the following files: 
mcatnlo_hwanal . f 
mcatnlo_hwdriver . f 
mcatnlo_hwhvvj . f 
Makefile 

We do not assume that the user will adopt the latest release of HERWIG (although 
we do recommend such a choice). For this reason, the files mcatnlojiwdriver.f 
and mcatnlo_hwhvvj . f must be edited, in order to modify the 'INCLUDE HER- 
WIGXX.INC command to correspond to the version of HERWIG the user is going 
to adopt. mcatnlo_hwdriver . f contains a set of read statements, which are necessary 
for the MC to get the input parameters (see sect. 3 for the input procedure); these 
read statements must not be modified or eliminated. Also, mcatnloJiwdriver . f 
calls the HERWIG routines which perform showering, hadronization, decays, and so 
forth; the user can freely modify this part, as customary in MC runs. Finally, the 
sample code mcatnlo_hwanal . f contains analysis-related routines: this file must be 
replaced by a file which contains the user's analysis routines. 

The Makefile must also be edited, in order to set two variables, HERWIGVER and 
HWUTI. The former variable must be set equal to the object file name of the version 
of HERWIG currently adopted (matching the one whose common blocks are included 
in the files above). The variable HWUTI must be set equal to the list of object files 
that the user needs in the analysis routines. The lists of files linked by Makefile are 
reported in app. A.l. See also sect. 5. 

2.1 Parton densities 

Since the knowledge of the parton densities (PDFs) is necessary in order to get the 
physical cross section, a PDF library must be linked. The possibility exists to link 
the CERNLIB PDF library (PDFLIB); however, we also provide a self-contained 
PDF library with this package, which is faster than PDFLIB. The user may link 
either PDF library; all that is necessary is to set the variable PDFLIBRARY (in the 
file MCatNLO . inputs) equal to THISLIB if one wants to link to our PDF library, 
and equal to PDFLIB if one wants to link to PDFLIB. Our PDF library collects the 
original codes, written by the authors of the PDF fits; as such, for most of the 
densities it needs to read the files which contain the grids that initialize the PDFs. 
These files, also provided with the present package, must either be copied into the 
running directory, or defined in the running directory as logical links to the physical 
files (by using In -sn). 

As stressed before, consistent inputs must be given to the NLO and MC codes. 
However, in ref. [1] we found that the dependence upon the PDFs used by the MC 
is rather weak. So one may want to run the NLO and MC adopting a regular NLO- 
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evolved set in the former case, and the default (LO) HERWIG set in the latter (the 
advantage is that this option reduces the amount of running time of the MC). In 
order to do so, the user must set the variable HERPDF equal to DEFAULT in the file 
MCatNLO . inputs; setting HERPDF=EXTPDF will force the MC to use the same PDF 
set as the NLO code. 

Regardless of the PDFs used in the MC run, users must delete the dummy 
PDFLIB routines PDFSET and STRUCTM from HERWIG, as explained earlier. 

3. Running 

It is straightforward to run the MC@NLO. First, edit 
MCatNLO. inputs 

and write there all the input parameters (for the complete list of the input parame- 
ters, see sect. 4). As the last line of the file MCatNLO . inputs, write 
runMCatNLO 

Finally, execute MCatNLO . inputs from the (bash) shell. This procedure will create 
the NLO and MC executables, and run them using the inputs given in MCatNLO . inputs, 
which guarantees that the parameters used in the NLO and MC runs are identical. 
Should the user only need to create the executables without running them, or to run 
the NLO or MC only, he/she should replace the call to runMCatNLO in the last line 
of MCatNLO . inputs by calls to 

compileNLO 

compileMC 

runNLO 

runMC 

which have obvious meanings (runXX also creates the XX executable). 

We stress that the input parameters are not solely related to physics (masses, 
CM energy, and so on); there are a few of them which control other things, such as 
the number of events generated. These must also be set by the user, according to 
his/her needs: see sect. 4. 

If the shell scripts are not used to run the codes, the inputs are given to the NLO 
or MC codes during an interactive talk-to phase; the complete sets of inputs for our 
codes are reported in app. A. 2. 

3.1 Event file 

The NLO code creates the event file. In order to do so, it goes through two steps; first 
it integrates the cross sections (the integration step) , and then, using the information 
gathered in the integration step, produces a set of events (the event generation step). 

The event generation step necessarily follows the integration step; however, for 
each integration step one can have an arbitrary number of event generation steps, i.e., 
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an arbitrary number of event files. This is useful in the case in which the statistics 
accumulated with a given event file is not sufficient. 

Suppose the user wants to create an event file; editing MCatNLO . inputs, the 
user sets BASES=0N, to enable the integration step, sets the parameter NEVENTS equal 
to the number of events wanted on tape, and runs the code; the information on 
the integration step (unreadable to the user, but needed by the code in the event 
generation step) is written on files whose name begin with FPREFIX, a string the user 
sets in MCatNLO . inputs; these files (which we denote as data files) have extensions 
.data. The name of the event file is EVPREFIX . events, where EVPREFIX is again a 
string set by the user. 

Now suppose the user wants to create another event file, to increase the statistics. 
The user simply sets BASES=0FF, since the integration step is not necessary any longer 
(however, the data files must not be removed: the information stored there is still 
used by the NLO code); changes the string EVPREFIX (failure to do so overwrites the 
existing event file), while keeping FPREFIX at the same value as before; and changes 
the value of RNDEVSEED (the random number seed used in the event generation step; 
failure to do so results in an event file identical to the previous one); the number 
NEVENTS generated may or may not be equal to the one chosen in generating the 
former event file(s). 

We point out that data and event files may be very large. If the user wants to 
store them in a scratch area, this can be done by setting the script variable SCRTCH 
equal to the physical address of the scratch area (see sect. 3.2). 

3.2 Results 

As in the case of standard HERWIG, the form of the results will be determined by 
the user's analysis routines. However, in addition to any files written by the user's 
analysis routines, the MC@NLO writes the following files: 

♦ FPREFIXNLOinput: the input file for the NLO executable, created according to 
the set of input parameters defined in MCatNLO . inputs (where the user also sets the 
string FPREFIX). See table 2. 

4 FPREFIXNLO.log: the log file relevant to the NLO run. 

♦ FPREFIXxxx . data: xxx can assume several different values. These are the data files 
created by the NLO code. They can be removed only if no further event generation 
step is foreseen with the currect choice of parameters. 

♦ FPREFIXMCinput: analogous to FPREFIXNLOinput, but for the MC executable. See 
table 4. 

♦ FPREFIXMC . log: analogous to FPREFIXNLO . log, but for the MC run. 

♦ EVPREFIX. events: the event file, where EVPREFIX is the string set by the user in 
MCatNLO. inputs. 

♦ EVP REF I Xxxx. events: xxx can assume several different values. These files are 
temporary event files, which are used by the NLO code, and eventually removed 
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by the shell script. They MUST NOT be removed by the user during the run (the 
program will crash or give meaningless results). 

By default, all the files produced by the MC@NLO are written in the running 
directory. However, if the variable SCRTCH (to be set in MCatNLO . inputs) is not 
blank, the data and event files will be written in the directory whose address is 
stored in SCRTCH. 

4. Script variables 

In the following, we list all the variables appearing in MCatNLO . inputs; these can be 
changed by the user to suit his/her needs. This must be done by editing MCatNLO . inputs. 

ECM The CM energy of the colliding particles. 

FREN The ratio between the renormalization scale, and a reference mass scale. 

FFACT As FREN, for the factorization scale. 

FRENMC As FREN; enters the MC-subtraction terms S| MC (see ref [1]). 

FFACTMC As FFACT; enters the MC-subtraction terms S| MC (see ref [1]). 

xMASS The mass (in GeV) of the particle x, with x=W,Z,U,D,S,C,B,G. 

IPROC Process number that identifies the vector bosons in the final states: see table 1 
for valid entries. 

PARTn The type of the incoming particle #n, with n=l,2. HERWIG naming conven- 
tions are used (P, PBAR, N, NBAR). 

PDFGROUP The name of the group fitting the parton densities used; the labeling conven- 
tions of PDFLIB are adopted. 

PDFSET The number of the parton density set; according to PFDLIB, the pair (PDFGROUP, 
PDFSET) identifies the densities. 

LAMBDAFIVE The value of A QCD , for five flavours and in the MS scheme. 

SCHEMEOFPDF The subtraction scheme in which the parton densities are defined. 

FPREFIX Our integration routine creates files with names beginning with the string 
FPREFIX. Most of these files are not directly accessed by the user; for more 
details, see sect. 3.1. 

EVPREFIX The name of the event file begins with this string; for more details, see sect. 3.1. 
NEVENTS The number of events stored in the event file, eventually processed by HERWIG. 
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WGTTYPE Valid entries are and 1. When set to 0, the weights are ±1. When set to 1, 
the weights are ±w, with w a constant such that the sum of the weights gives 
the total NLO rate. 

RNDEVSEED This is the seed for the random number generation is the event generation step; 

must be changed in order to obtain statistically-equivalent but different event 
files. 

BASES Controls the integration step; valid entries are ON and OFF. At least one run 
with BASES=0N must be performed. 

PDFLIBRARY Valid entries are PDFLIB and THISLIB. In the former case, the local version of 
PDFLIB is used to compute the parton densities, whereas in the latter case 
the densities are obtained from our self-contained faster package. 

HERPDF If set to DEFAULT, HERWIG uses its internal PDF set (controlled by NSTRU), 
regardless of the densities adopted at the NLO level. If set to EXTPDF, HERWIG 
uses the same PDFs as the NLO code. 

HWPATH The physical address of the directory where the user's preferred version of 
HERWIG is stored. 

SCRTCH The physical address of the directory where the user wants to store the data 
and event files. If left blank, these files are stored in the running directory. 



5. Makefile variables 

Before running the package, the user must edit the Makefile, in order to set the 
following variables. Further changes of the Makefile are necessary only if one wants 
to change the HERWIG version linked, or other files must be added for new features 
in the analysis routines. 

HWUTI This variable must be set equal to a list of object files, needed by the analysis 
routines of the user (for example, HWUTI=objl.o obj2.o obj3.o is a valid 
assignment) 

HERWIGVER This variable must to be set equal to the name of the object file corresponding to 

the version of HERWIG linked to the package (for example, HERWIGVER=herwig64 . o 
is a valid assignment) 



A. Running the package without the shell scripts 

In this appendix, we describe the actions that the user needs to take in order to run 
the package without using the shell scripts, and the Makefile. 
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A.l Creating the executables 

An MC@NLO run requires the creation of two executables, for the NLO and MC 
codes respectively. The files to link depend on whether one uses PDFLIB, or the 
PDF library provided with this package; we list them below: 

• NLO without PDFLIB: mcatnlo_vbmain . o mcatnlo_vbxsec . o mcatnlo_date . o 
mcatnlo_int . o mcatnlo_uxdate . o mcatnlo_uti . o mcatnlo_str . o 
mcatnlo_pdf tomlm. o mcatnlo_libof pdf . o dummies. o SYSFILE 

• NLO with PDFLIB: mcatnlo_vbmain.o mcatnlo_vbxsec . o mcatnlo_date . o 
mcatnlo_int . o mcatnlo_uxdate . o mcatnlo_uti . o mcatnlo_str . o 
mcatnlo_mlmtopdf .o dummies . o SYSFILE CERNLIB 

• MC without PDFLIB: mcatnlo_hwanal . o mcatnlo_hwdriver . o mcatnlo_hwhvvj . o 
mcatnlo_str . o mcatnlo_pdf tomlm. o mcatnlo_libof pdf . o dummies . o HWUTI 
HERWIGVER 

• MC with PDFLIB: mcatnlo_hwanal . o mcatnlo_hwdriver . o mcatnlo_hwhvvj . o 
mcatnlo_str.o mcatnlo_mlmtopdf . o dummies . o HWUTI HERWIGVER CERNLIB 

Here, SYSFILE must be set either equal to alpha. o, or to linux.o, or to sun.o, 
according to the architecture of the machine on which the run is performed. For 
any other architecture, the user should provide a file corresponding to alpha. f etc., 
which he/she will easily obtain by modifying alpha. f. The variables HWUTI and 
HERWIGVER have been described in sect. 5. Finally, the variable CERNLIB must be 
set in order to link the local version of CERN PDFLIB. To create the object files 
eventually linked, static compilation is always recommended (for example, g77 -Wall 
-f no-automatic on Linux). 

A. 2 The input files 

In this appendix, we describe the inputs to be given to the NLO and MC executa- 
bles. When the shell scripts are used to run the MC@NLO, two files are created, 
FPREFIXNLOinput and FPREF I XMC i nput , which are read by the NLO and MC ex- 
ecutable respectively. We start by considering the inputs for the NLO executable, 
presented in table 2. The variables whose name is in uppercase characters have been 
described in sect. 4. The other variables are assigned by the shell script. Their 
default values are given in table 3. Users who run the package without the script 
should use the values given in table 3. The variable zi controls, to a certain ex- 
tent, the number of negative- weight events generated by the MC@NLO (see ref. [1]). 
Therefore, the user may want to tune this parameter in order to reduce as much as 
possible the number of negative-weight events. We stress that the MC code will not 
change this number; thus, the tuning can (and must) be done only by running the 
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'FPREFIX' 


! prefix for BASES files 


'EVPREFIX' 


! prefix for event files 


ECM FFACT FREN FFACTMC FRENMC 


! energy, scalefactors 


IPROC 


' 2850/60/70/80=WW/ZZ/ZW+/ZW- 


WMASS ZMASS 


! M_W, M_Z 


UMASS DMASS SMASS CMASS BMASS GMASS 


' nnark and fdnon masses 


'PARTI' 'PART2' 


! hadron types 


'PDFGROUP' PDFSET 


! PDF group and id number 


LAMBDAFIVE 


! Lambda_5, <0 for default 


'SCHEMEOFPDF' 


! scheme 


NEVENTS 


! number of events 


WGTTYPE 


! => wgt=+l/-l, 1 otherwise 


RNDEVSEED 


! seed for rnd numbers 


zi 


! zi 


nitii! nitn 2 


! itmxl,itmx2 



Table 2: Sample input file for the NLO code. FPREFIX and EVPREFIX must be understood 
with SCRTCH in front (see sect. 4). 



Variable 


Default value 


zi 


0.1 


nitnj 


10/0 (BASES=0N/0FF) 



Table 3: Default values for script-generated variables in FPREFIXNLOinput. 

NLO code. The variables nitnj control the integration step (see sect. 3.1), which can 
be skipped by setting nitnj = 0. If one needs to perform the integration step, we 
suggest setting these variables as indicated in table 3. 

We now turn to the inputs for the MC executable, presented in table 4. The 
variables whose names are in uppercase characters have been described in sect. 4. 
The other variables are assigned by the shell script. Their default values are given 
in table 5. The user can freely change the values of esctype and pdftype; on the 
other hand, the value of beammom must always be equal to half of the hadronic CM 
energy. 
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'EVPREFIX events' 


' pvpnt filp 


NEVENTS 


! numbpr of pvpnts 


esctype 


' 0->EMSCA=sartfs)-2*nT l->EMSCA=sartfs) 


Ddf tvoe 


! 0->Hprwig PDFs, 1 othprwisp 


'PARTI' 'PART2' 


! hadron typps 


beanunoni beanunoni 


! bpam mompnta 


IPROC 


! 2850/60/70/80=WW/ZZ/ZW+/ZW- 


'PDFGROUP' 


' PDF eroun (1) 


PDFSET 


! PDF id numbpr (1) 


'PDFGROUP' 


! PDF group (2) 


PDFSET 


! PDF id numbpr (2) 


LAMBDAFIVE 


! Lambda_5, <0 for default 


WMASS WMASS ZMASS 


! M_W+, M_W-, M_Z 


UMASS DMASS SMASS CMASS BMASS GMASS 


! quark and gluon masses 



Table 4: Sample input file for the MC code, resulting from setting HERPDF=DEFAULT, which 
implies pdf type=l. Setting HERPDF=EXTPDF results in an analogous file, with pdf type=0, 
and without the lines concerning PDFGROUP and PDFSET. EVPREFIX must be understood 
with SCRTCH in front (see sect. 4). 



Variablp 


Dpfault valup 


esctype 





pdf type 


0/1 (HERPDF=DEFAULT/EXTPDF) 


beammom 


EMC/2 



Table 5: Default values for script-generated variables in MCinput. 
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